No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage and retrieval system, without permission in writing from the publisher. However, you are permitted to make copies of this work, printed or otherwise, as long as said copies are for your personal use only.
Introduction
------------
Last time, we designed a profile dialog and was able to extract information from it. This time, we'll take the profile dialog one step further by introducing a "hit handler". Hit handlers allow you to interact directly with the dialog. You can do things like check all the edit text fields for a value before dismissing the dialog. We will also make some additions to our Profile dialog, including a popup menu.
Design
------
This tutorial assumes that you know the basics of how to use ResEdit. If you don't, refer to DP Tutorial Pt.1, or to the ResEdit reference manual.
1. Create a new MicroPhone settings document called "DP Test2".
2. Open this settings document with ResEdit and create a new DLOG called "Profile" with the ID 7777. Create a corresponding DITL of the same ID.
3. Create the following dialog items:
1 - "OK" button
2 - "Cancel" button
3 - "Other" button
4 - "Name" edit field
5 - "Password" edit field
6 - "Phone" edit field
7 - "# of Tries" useritem
8 - "Name" static field
9 - "Password" static field
10 - "Phone" static field
11 - "# of Tries" static field
This dialog exists already in the DP Tutorial Pt.2 settings document, so you don't really need to create it. Take a look at the dialog using ResEdit to get a feel for how the dialog has been designed.
A Simple Example
----------------
To recap what was discussed in the previous tutorial, here is a simple example of how to interact with a dialog. This script, places defaults values into the dialog, displays the dialog, and checks if the OK button has been hit. The script is called "Dialog1" in the DP Tutorial Pt.2 settings document.
Remark "--- Dialog1 ---"
Remark "--- puts default values into dialog items and"
Remark "--- displays the dialog named Profile"
Remark "--- and returns new values of the OK button is clicked"
Remark "---"
Remark "--- configure the default values"
Set Variable * tries from Expression "'1^M2^M3^M4^M5'"
Set Variable * theName from Expression "'Penny Copper'"
Set Variable * thePassword from Expression "'nickel'"
Set Variable * thePhone from Expression "'555-1212'"
Set Variable * theTries from Expression "'3'"
Remark "--- display the dialog"
Set Variable * d0 from Expression "'Profile'"
Set Variable * d4 from Expression "'4◊' & theName"
Set Variable * d5 from Expression "'5◊' & thePassword"
Set Variable * d6 from Expression "'6◊' & thePhone"
Set Variable * d7 from Expression "'7◊userPop ' & theTries & '^M' & tries"
Set Variable * dResult from Expression "MPDialogerPro(d0,d4,d5,d6,d7)"
If Expression "ItemFetch(dResult,'^M',1) = 'OK'"
Alert * OK "'The OK button was clicked.'"
End If
All of the values in the dialog are stored in the variable called dResult, in a carriage return delimited list. The first item of the dialog is the OK button. MPDialogerPro will return the name of the button that is clicked, which is why we look for 'OK'. If the Cancel button had been clicked, the second value in dResult's carriage return delimited list would have been 'Cancel', and the first item would have been blank.
Hit Handlers
------------
A hit handler allows you to do things to a dialog without causing the dialog to be dismissed in the process. For example, there is a button called "Other" in our example dialog. If you ran the above script and clicked on that button, nothing would happen. Clicking on "Other" won't even dismiss the dialog, since as a default, only items 1 and 2 in a dialog will dismiss the dialog.
To include a hit handler with a dialog, put the word 'on' and the name of the hit handler along with the name of the dialog, with a carriage return between, like this:
Set Variable * d0 from Expression "'Profile^Mon Profile_handler'"
Whenever anything happens that causes a hit in the dialog, the script "Profile_handler" will be executed and a variable called "dialog" will be generated, pointing to the dialog that received the hit. Hits can be caused by clicking items, moving the dialog, or even putting the dialog in the background or bringing it to the foreground.
Here, we modify our script and introduce the hit handler:
Remark "--- Dialog2 ---"
Remark "--- puts default values into dialog items and"
Remark "--- displays the dialog named Profile"
Remark "--- and uses a hit handler called Profile_handler"
Remark "---"
Remark "--- configure the default values"
Set Variable * tries from Expression "'1^M2^M3^M4^M5'"
Set Variable * theName from Expression "'Penny Copper'"
Set Variable * thePassword from Expression "'nickel'"
Set Variable * thePhone from Expression "'555-1212'"
Set Variable * theTries from Expression "'3'"
Remark "--- display the dialog"
Set Variable * d0 from Expression "'Profile^Mon Profile_handler'"
Set Variable * d4 from Expression "'4◊' & theName"
Set Variable * d5 from Expression "'5◊' & thePassword"
Set Variable * d6 from Expression "'6◊' & thePhone"
Set Variable * d7 from Expression "'7◊userPop ' & theTries & '^M' & tries"
Set Variable * dResult from Expression "MPDialogerPro(d0,d4,d5,d6,d7)"
Note that the last thing we do now in the script is called MPDialogerPro. Everything else will be handled by the hit handler assigned to the dialog. And here's the hit handler:
Remark "--- Profile_handler ---"
Remark "--- hit handler for Profile dialog"
If Expression "itemHit = '0'"
Remark "--- this is an opportunity to initialize the dialog"
Remark "--- before it is actually displayed"
Remark "--- but, we don't need to do anything for this example"
Else If Expression "itemHit = '1'"
Remark "--- the OK button was clicked"
Alert * OK "'You clicked OK.'"
Else If Expression "itemHit = '2'"
Remark "--- the Cancel button was clicked"
Alert * OK "'You clicked Cancel.'"
Else If Expression "itemHit = '3'"
Remark "--- the Other button was clicked"
Alert * OK "'You clicked the Other button'"
End If
Other Examples
--------------
There are several other examples in the DP Tutorial Pt.2 settings document. They demonstrate ways in which the hit handler can fine-tune the way the dialog is handled.
Dialog3 - demonstrates the ability to change the behavior of a button. In this example, the OK button no longer dismisses the dialog, but the Other button does. This is accomplished by the following lines in the script:
Do XCMD * MPChangerPro "dialog,'1◊NoDismiss'"
Do XCMD * MPChangerPro "dialog,'3◊Dismiss'"
MPChangerPro is an XCMD that works in conjunction with MPDialogerPro, allowing you to change the contents of a dialog on the fly. Note that "dialog" is a variable that always points to the dialog that received the hit. The syntax for MPChangerPro is:
dialog,'item◊command'
where dialog is a pointer to the dialog. This value is generated automatically whenever a dialog receives a hit. Item is the number of the item in the dialog. Command is what you want MPChangerPro to do to the item.
Dialog4 - demonstrates the ability to make changes to the values in a dialog. In this example, if you click the Other button, it changes the phone number in the edit field to the current time. This is accomplished by the following line in the script:
Do XCMD * MPChangerPro "dialog,'6◊' & String(Hour) & String(Minute)"
You are telling MPChangerPro to pass the current hour and minute to item number six in the dialog.
